X3D-Edit for Extensible 3D (X3D) Graphics - README

Don Brutzman (brutzman at nps.navy.mil)
翻译：web3d中文基地
2007年冬的时候，发布了基于Netbeans的完全重构的X3D-Edit 3.2版，可以到https://savage.nps.edu/X3D-Edit/处了解更多信息。

自动安装 | 目标 | 状态 | 国际化 (i18n) | 安装设置 | 下载更新 | 特性 | 细节 | 用法 | 简化形式 | 开发者 | Bug修复

目标

X3D-Edit是一款图形化可扩展 3D (X3D)文件编辑器，让你可以很简单地进行无错式编辑、创作与有效性验证X3D/VRML场景图文件。上下文敏感工具提示对每个X3D节点与属性提供简要的概况。让你可以很简单地进行无错式编辑、创作与验证X3D/VRML场景图文件。上下文敏感工具提示对每个X3D节点与属性提供简要的概述。这些提示简化了创作。并对新手和专家级用户同样具有提高理解的作用。

X3D-Edit自动安装器 可在线进行，各种操作系统（Windows, Mac, Linux, Solaris及其它 Unix）下都有。

X3D-Edit采用《X3D 3.1 文档类型定义（DTD）》中定义的X3D 3.1标签集，组合了Sun的Java，IBM的Xeena XML editor及编辑器Profile配置文件。

查看X3D帮助以获取更多的X3D资源。

状态

X3D-Edit实现可扩展3D（X3D）-下一代虚拟现实建模语言（VRML 200X）-标签集。X3D-Edit也试着进行各种X3D图形渲染及转换的实现。

软件与实例最近的更新：查看 build.date.X3D-Edit.txt.

现在的3.1版本，匹配X3D 3.0 国际规范 (2004 夏) ，并加入了X3D 修正案 第一版中的一些组件 (2005 冬)。（注：2007年冬的时候，发布了基于Netbeans的完全重构的X3D-Edit 3.2版，可以到https://savage.nps.edu/X3D-Edit/处了解更多信息。）

完成了的v3.1组件：

还在进行的有：测试X3D Schema (x3d-3.1.xsd)，通过几千个X3D实例，做成了XML Spy的一个项目文件。

功能改善：

国际化(i18n):

"工具是怎样组织起来的" 图示： XML Tool Relationships for X3D.

教学: 我们在使用X3D-Edit来教授一门VRML/X3D 课程。对减少内容bug及消除VRML语法特性真的有帮助。2000年一月份到三月份对这门课程采用beta版教学的时候，讲完VRML 2.0资源手册中材料的速度比以前的方式快了一个星期。我们采用X3D-Edit当前版本达到了近似的高效的过程。资源手册中实例（共270个）的X3D版本可在Vrml 2.0资源手册实例X3D版站点上获得。

欢迎作出对X3D-Edit安装/不稳定相关的建议与改进。可以在www-vrml 邮件列表中讨论该工具。

Mac上的介绍在README.X3D-Edit.Mac.txt中。 感谢mac爱好者Steve Guynup (guynups@gra.com)

安装设置

你需要以具有administrator权限的身份登录，以便执行其中的一些安装。

推荐安装：自动安装器。 X3D-Edit AutoInstaller 可以在各种操作系统下进行(Windows, Mac, Linux, Unix/Solaris).

如果已经安装过了，且系统中有了VRML插件（按照步骤1），你可以跳到步骤7，直接更新到新版本，并简单提取上面的更新。

如果你选择手动安装X3D-Edit，按照步骤1-6来，不要用自动安装器。

  1. 给你的浏览器选择一款免费的VRML插件装上。以下这些插件可以和Netscape 及 Internet Explorer任意组合使用。
    看看是否你的VRML浏览器安装成功，可以去查看HelloWorld.wrl示例场景。
  2. 安装Java 使用一个在线发布的版本。（需要Java环境来运行Xeena工具）在安装的时候，你需要接受非限制性Java许可。
    如果Java已经安装了，你可以省了下载这个步骤。可以打开命令窗口，敲入
    		c:\>  java -version
    来测试Java是否安装。
  3. （这里放弃了原作者内容，改成本站修正版说明）
    (右键另存，下载后扩展名改为7z)X3D-Edit3.1修正版 原作者设想将整个软件置于系统根目录，这种思路太不符我们的习惯，我做了一些修改，让其可以自由的放置，当然，放在中文目录下是大大的有问题的。
    正常安装了JDK或JRE后，系统注册表中会加入相应信息，不需额外指定Java_home。但老版本或绿色版则必须手动指定Java环境的路径。所以大家在使用前就需要注意这样的问题。可以直接在命令文件中Set java_home，也可以在系统变量中追加java_home这一项。Java路径选JDK的安装路径，如“C:\Program Files\Java\jdk1.7.0”。
    正常使用请直接点击X3D-Edit-Chinese.bat或X3D-Edit.bat，tools目录下一些格式转换工具，暂时没实际使用过，Vrml97ToX3dNist.bat这个命令可以用，但里面其他的配置文件基本上都是有问题的，熟悉者可自行修正。
    另外，X3D-EDIT里面那几个XSL转换的样式文件路径还有些问题，暂时不能正常使用。
    注：这个软件虽然比较简单，但对我们学习X3D确实有莫大的帮助。它可以帮我们了解整个X3D的应用体系，以及具体的使用方法，最重要的是可以保证无错。
    相关链接： http://www.alphaWorks.ibm.com/tech/xeena (~5MB).

  4. 略
  5. 安装 GeoVRML.
  6. 安装 DIS-Java-VRML.

    7. 下载更新包

  7. 从http://www.web3d.org/x3d/content/X3D-Edit.zip下载X3D-Edit更新包(~30 MB)。

  8. 推荐安装： 下载X3d实例包

    X3D实例可以在线查看：
    http://www.web3d.org/x3d/content/examples 及
    http://www.web3d.org/x3d/content/examples/Vrml2.0Sourcebook.

  9. 推荐安装： 下载ConformanceNist实例包 (~150 MB)，从
    http://www.web3d.org/x3d/content/examples/ConformanceNistSuite.zip

    ConformanceNist实例 也可在线查看: http://www.web3d.org/x3d/content/examples/ConformanceNist.
  10. 全部完成！
    • 是时候运行X3D-Edit了
    • 查看 用法 以了解更多的X3D-Edit指导
    • 查看 Bug修复 如果你在X3D-Edit使用中遇到了麻烦
    • 查看 X3D/VRML 帮助 了解更多的X3D资源
    • 欢迎反馈!

特性

细节

X3D-Edit采用简化（compact 注：超出译者知识范围，不知是否翻译准确）XML标签集，由X3D简化文档类型定义（DTD）

3.0版与
各历史版本
X3D-Edit v3.0 X3D国际规范草案。在x3d-dtd-changelog.txt文件中详细描述了修改情况。
X3D-Edit v2.4包含对X3D规范最终委员会草案进行最终测试的DTD，该DTD重编为3.0。v2.4也包含了一些重要的标签集变化：原型接口/原型正文、容器域（containerField）、不能设置仅输入/仅输出访问类型的域、加上更严格的X3dToVrml97.xslt转换验证检测。
X3D-Edit v2.3 包含了Geometry2D, MultiTexture and Event Utility节点，以及IS/connect, 域/域值 USE, 类型与访问类型重命名等标签集的重要变化。
X3D-Edit v2.2 包含了VRML导入能力。
X3D-Edit v2.1 包含
  • 更多简化标签集：去除了<proxy>，同时用属性 containerField 表示默认的父-子关系名称。，<proxy>节点将被视为非法（用USE="nameTargetDEF"属性代替）
  • 保留了全局“class”属性，以便将来使用XML层叠样式表（CSS），同HTML样式表使用类似。
  • 导入/导出体验的支持，用于跟踪进/出内联节点（Inline）的值。
  • 不再允许<USE> 元素，由于缺乏对节点与属性值的类型检测，而且目前是一项多余功能。新标准中采用@USE属性代替，如<Shape USE="MyShapeNode"/>
同时，使用Xeena 的1.2 EA 版本.
X3D-Edit v2.0 包含了节点类型（nodeType）与访问类型（accessType）属性的变更及属性值的有效性验证。
X3D-Edit v1.8 包含头部标签集的变更。
X3D-Edit v1.7 包含DIS-Java-VRML, GeoVRML 与 H-Anim 节点支持。
   现在使用 x3d-compact.dtd 标签集 (无包裹标签)。
v1.6 对应于 x3d-compromise.dtd (October 2000) + 完整的资源手册实例、 KeySensor + StringSensor + NURBS。
   这个版本及对应的实例都使用 x3d-compromise.dtd，带包裹（wrapper）标签。可下载： X3D-Edit-1.6.zip 与 X3D-Examples-1.6.zip。
v1.5 对应x3d-compromise.dtd (September 2000) + GeoSpatial + H-Anim + DIS-Java-VRML + 扩展
v1.4 对应x3d-compromise.dtd (July 2000) + 扩展
v1.3 对应x3d-compromise.dtd (May 2000)
v1.2 对应x3d-compromise.dtd (April 2000)
v1.1 对应x3d-draft.dtd (February 2000)
原始版本: 1 November 1999
软件作者
Don Brutzman brutzman at nps.navy.mil
发布包
http://www.web3d.org/x3d/content/X3D-Edit.zip
实例内容
X3D-Edit是一款完全的测试性工具。X3D-Edit被用来创作一套多元化的X3D/VRML场景，如下：
实例帮助
http://www.web3d.org/x3d/content/examples
http://www.web3d.org/x3d/content/examples/Vrml2.0Sourcebook
http://www.web3d.org/x3d/content/examples/ConformanceNist
http://savage.nps.edu/Savage
屏幕截图
X3D-EditSampleScreenSnapshot.png用户界面
examples/GeoSpatial/newGeoSpatialScene.png GeoVRML节点
examples/HumanoidAnimation/NancyNativeTags.png H-Anim节点
Icon概要图
IconSheet-1.pdf, IconSheet-2.pdf, IconSheet-3.pdf, IconSheet-4.pdf
许可
X3D-Edit中的文件是X3D任务组的开源公共领域的产品。
在下载或安装那些工具每一部分的时候，提供非严格性Sun Java许可及对Xeena非严格性IBM许可。
IBM 已经慷慨的允许Web3D组织在WEB3D/X3D软件开发工具包(SDK)中包含Xeena。

用法

  1. X3D-Edit启动快捷方式
  2. Windows shell调用：
  3. Unix shell调用：
  4. Xeena细节. 好东西仍然值得去挖掘： 安装 README的本地拷贝帮您查找安装故障。 通过阅读 帮助 (用户指导)，你可以了解所有与用户界面相关的内容。 其它的任何东西也许在 常见问题集(FAQ)页面中可以找到答案。

简化形式

这部分内容不再属于目前X3D版本。你可以放心的忽略它，简化形式与折衷形式内容的文档仅仅作为存档目的。

你可以轻易的对“老化”了的内容进行简化，即通过使用X3dUnwrap，移除"wrapper 标签" (<children> <appearance> <geometry> 等)。这也会让你从早期版本升级到X3D-Edit v 1.7。

从顶部菜单中选择“Tools”-“Process XSL”。用显示的X3dUnwrap.xsl样式表来展开你的场景。备份你的原始文件（或以不同文件名保存）是个好主意。Process XSL窗口可以左右伸缩，这样更易查看。

样式表还会标签集文档类型定义（DTD）从x3d-compromise.dtd更新到x3d-compact.dtd。

示例截图，显示 "之前" (折衷的包裹标签，X3D-Edit v1.6) 及 "之后" (简化的展开形式，X3D-Edit v1.7) 的场景图。

开发者

接下来是与这个项目有关的一些微小细节。 这个主要是文档目的，常规使用是不需要的。

开发者的可选用法

Besides X3D-Edit.bat, example Xeena editor invocations under Windows follow. Edit to match your your locally installed subdirectories as needed.

<> C:\ibm\Xeena> xeena.bat -dtd c:\www.web3d.org\x3d\content\x3d-compromise.dtd -root X3D C:\ibm\Xeena> xeena.bat -dtd c:\www.web3d.org\x3d\content\x3d-compromise.dtd -root X3D -xml c:\www.web3d.org\x3d\content\examples\AllVrml97Nodes.xml

There are many example invocations and shortcuts in the Makefile.

更换安装目录

Not recommended (which means "skip this section"). If you insist on changing the installation directory (!) then you will need to edit the second line (DOCTYPE) of x3d-compromise.dtd, and you will also need to edit the following files: x3d-compromise.profile.X3D-Edit-1.6, x3d-compromise.profile, X3D-Edit-1.6.bat, X3D-Edit.bat and Makefile (if used) to match your local directory structure. You will likely have to edit the examples as well, though if you are connected to the network, Xeena will try to find the website version of the DTD.

XSL样式表及转换工具

Bug修复

Many bugs are avoided altogether (especially Windows ME and 98) by using the X3D-Edit Auto Installer for various operating systems (Windows, Mac, Linux, Unix/Solaris).

0. X3D-Edit can't open example scenes due to being disconnected from the network. The underlying Xeena tool can't be modified to substitute local DTDs for online DTDs, causing a validation error when opening most scenes when offline. The best correction to this problem is simply to connect to the network.

1. Xeena/X3D-Edit works under JDK 1.4, except for the "Allowed Nodes" pane. Workarounds: use the other panes, install the X3D-Edit Auto Installer version, or supplement JDK 1.4 with JDK 1.3.1_09 instead.

2. A common installation problem follows. This can occur under Windows 95, Windows 98 or Windows Millenium (ME). The fix is the same either way. 

] If you're running Windows 95/98/ME, and encounter an "Out of environment space" 
] error, then you'll need to increase the size of the environment table.  
] You can do this at the command line (which is temporary) or by editing 
] a configuration file to make a permanent change (which requires restarting 
] your computer). 
] 
]      To temporarily increase environment space for X3D-Edit.bat, 
]      first enter the following command at the DOS prompt: 
] 
]         C:\www.web3d.org\x3d\content>   command /e:8192 
] 
]         C:\www.web3d.org\x3d\content>   X3D-Edit 
] 
]      To permanently increase environment space, 
]      add the following line to your C:\CONFIG.SYS file,
]      save all files, and then restart (reboot) your system: 
] 
]          shell=command.com /e:8192 /p 
] 
]      Once you've increased the size of the environment table,
]      try running Xeena again.  If there is still a problem,
]      please cut/paste the command-window text into an email and
]      report the problem.

Alternative for Windows Millenium (ME) from Tom Greenwald, NPS. 

] For both Xeena and X3D-Edit I had to right click on the icon, left click
] on properties, click the memory tab, set the initial environment to
] 4096, set extended (XMS) memory to 8192, and set MS-DOS protected mode
] (DPMI) memory to 8192.

You may need to reboot your computer for these changes to take effect. You will also have to repeat this step whenever you update X3D-Edit, so you may prefer the permanent change above.

3. If you use the older version 1.1 of Xeena (instead of 1.2EA), the following errors appear: 


	C:\www.web3d.org\x3d\content>c:\ibm\Xeena\xeena.bat 
	  -dtd "c:\www.web3d.org\x3d\content\x3d-compromise.dtd"
	  -root X3D 
	  -xml "c:\www.web3d.org\x3d\content\examples\newScene.xml"
	
	Syntax error
	Syntax error
	running Xeena with Java 2
	Exception in thread "main" java.lang.NoClassDefFoundError:
	com/ibm/hrl/xmleditor/Xeena

To fix this problem: uninstall Xeeena 1.1, install Xeena 1.2 EA, and again extract X3D-Edit.zip (to correct the Xeena CLASSPATH bug). Or simply uninstall X3D-Edit and use the autoinstaller instead.

4. After importing a VRML97 scene, the XSL buttons do not work.

The following obscure message may appear in the console: 

 java.lang.StringIndexOutOfBoundsException: String index out of range: -1

Fix: save the imported scene as a file. This may require renaming your scene if it was originally a read-only file (such as newScene.x3d). The XSL buttons now work. See above for more instructions on using the VRML97 Import capability.

5. Insufficient memory.

You will need 128MB of RAM or more. Yes, 128.

6. The window goes blank and locks up before displaying a scene.

This is likely a DOCTYPE/DTD problem: Xeena is attempting to retrieve the DOCTYPE/DTD via the network, without success. When using Java 1.3 or earlier, this problem can only be fixed by replacing the DOCTYPE/DTD or else by connecting to the network, thus gaining access to the final DTD url.

Fixes and workarounds:

7. You want to use an http proxy server.

The http proxy server feature is for loading a file via the Web. Not a very common setting, but nice to have nevertheless.

You will need to uncomment and update the line in X3D-Edit's modified C:\IBM\Xeena\Xeena.bat for set PROXY_SETTINGS. Warning: we've had trouble with this feature under Windows 98.

8. Some developers might not have Make installed...

Make is not necessary to run X3D-Edit, it is only used for X3D-Edit source development. The Makefile is being replaced by an Ant build file.

Make is available via the Cygnus distribution of GNU Utilities for PCs at http://sourceware.cygnus.com/cygwin. The Cygwin distribution provides Unix command line and utilities on Windows 95/98/NT/2000. Don't forget to upgrade your PATH with something like C:\cygnus\cygwin-b20\H-i586-cygwin32\bin;. Once Make is installed, edit the Makefile filename/directory definitions to match your local installation. There are a bunch of alternate example invocations in the Makefile if you know how to grok Make.

9. X3D-Edit can't seem to find the correct version of Java.

Set the JAVA_HOME environment variable to the installation directory for Java on your system and X3D-Edit will use Java accordingly.

10. No X3D scene appears in the browser.

Install a VRML or X3D plugin in your Web browser.

11. Internet Explorer (IE) blocks viewing the 3D scene.

The following screen snapshots illustrate this problem and 2 solutions.

When the plugin is blocked from showing content, the following warning bar appears near the top of the browser. Right click and select "Allow blocked content..." then select "Yes" to confirm.

Windows Xp Allow Blocked Content To Run For One Session

Correct integration of the plugin then appears:

Windows Xp Allow Blocked Content To Run Result

You can permanently reset this permission by selecting Internet Explorer -> Tools -> Internet Options... -> Advanced and then under Security select "Allow active content to run in files on My Computer" as follows:

Windows Xp Allow Blocked Content To Run Internet Options

Similar selections can be made for automatically running content from a CD, over the Internet, etc.

12. How do I quickly update X3D-Edit and examples?

Menu shortcuts are provided under windows to easily retrieve updates. Always extract all .zip files to the C:\ root directory.

Windows Start Program Menus X3d Updates

13. IBM Haifa was very attentive in responding to bug reports regarding Xeena, the interface tool. Unfortunately, despite the popularity of Xeena, their team is no longer working on this tool. We hope to fix known Xeena bugs someday. Nevertheless it still usually works fine for X3D-Edit.

Revised: 7 March 2007

Maintained by Don Brutzman (brutzman at nps.navy.mil)

This page is available online at http://www.web3d.org/x3d/content/README.X3D-Edit.html